/****************************************************************************
**
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation
**
**
** $QT_BEGIN_LICENSE:BSD$
** You may use this file under the terms of the BSD license as follows:
**
** "Redistribution and use in source and binary forms, with or without
** modification, are permitted provided that the following conditions are
** met:
**   * Redistributions of source code must retain the above copyright
**     notice, this list of conditions and the following disclaimer.
**   * Redistributions in binary form must reproduce the above copyright
**     notice, this list of conditions and the following disclaimer in
**     the documentation and/or other materials provided with the
**     distribution.
**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
**     the names of its contributors may be used to endorse or promote
**     products derived from this software without specific prior written
**     permission.
**
** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
** $QT_END_LICENSE$
**
****************************************************************************/



#ifndef DESCRIPTOREXEXAMPLES_SYMBIAN_H
#define DESCRIPTOREXEXAMPLES_SYMBIAN_H

// System Includes.
#include <e32std.h>
#include <f32file.h>


/*!
* This class declares a protocol that examples use to render the results of
* example methods. The implementing class holds a buffer where text can be
* appended. GetViewBuffer() returns descriptor to internal buffer. UpdateView()
* renders the content to the destination device and may reset internal buffer.
*/
class MResultViewer
    {
    public:
        /*!
         * Implementing method shall return a modifiable descriptor pointer
         * where text can be appended.
         */
        virtual TPtr GetViewBuffer()=0;

        /*!
         * Implementing method shall render the content to output so that user
         * can view the results. As a side effect, the TPtr returned by method
         * GetViewBuffer() may come obsolete and should be queried again before
         * usage.
         */
        virtual void UpdateView()=0;
    };


/*!
* This class declares example methods that describe the usage of descriptors and
* related APIs.
*/
class CDescriptorExamples
    {
    public:

        /*!
        * This constructor instantiates an object whose example methods are used
        * to demonstrate descriptors and related APIs.
        *
        * @param aViewer MResultViewer object where results are to be written.
        *                This doesn't take ownership of given viewer so it has
        *                to be deleted after this object is no more used.
        */
        CDescriptorExamples(MResultViewer *aViewer) : iViewer(aViewer) {};

        //----------------------------------------------------------------------
        // Methods below are implemented in DeclaringDescriptors.cpp

        /*!
        * Examples in this method describes how to declare each descriptor type
        * as an automatic variable (object allocated to stack). Following issues
        * are covered:
        *
        * - how to declare each descriptor type to stack
        * - using code blocks to deallocate unneeded automatic variables
        */
        void OnStack();

        /*!
        * Examples in this method describes how to allocate descriptors from
        * heap.
        */
        void OnHeapL();

        /*!
        * This example method describes how to declare literals. Following
        * issues are covered:
        *
        * - declaring literal with macro _LIT
        * - declaring literal with macro _L
        * - declaring unicode characters in literals
        */
        void Literals();

        //----------------------------------------------------------------------
        // Methods below are implemented in ManipulatingDescriptors.cpp

        /*!
        * This example demonstrates usage of non-modifying methods declared the
        * base class of all descriptor, TDesC.
        */
        void NonModifyingMethods();

        /*!
        * This example demonstrates usage modifying methods declared the base
        * class of modifying descriptors, TDes.
        */
        void ModifyingMethodsL();

        /*!
        * This example demonstrates how to convert string data encoded with one
        * character set to unicode and vice versa. Conversion of SMS data is
        * used as and example.
        */
        void CharacterConversionsL();

        /*!
        * This example demonstrates how numbers in string format can be parsed
        * to binary representation.
        */
        void LexicalAnalysis();

        //----------------------------------------------------------------------
        // Methods below are implemented in OtherBuffers.cpp

        /*!
        * The first example in this method demonstrates how circular buffer,
        * First In First Out (FIFO) data structure, is used manipulate character
        * data. Each item in the FIFO is instance of TText that is 16 bit
        * character code unicode build and 8 bit character in non-unicode build.
        * 
        * The second example in this method extends the usage to a bit more
        * complex type than a 8 or 16 bit number. An example class is used as an
        * item in structure.
        */
        void CircularBuffersL();

        /*!
        * This method demonstrates how flat dynamic buffer (CBufFlat) is used to
        * store and alter binary data. 8-bit character data is used as an
        * example data.
        * 
        * Data in CBufFlat lies in one contiguous heap cell. CBufFlat extends
        * the heap cell used to store the contents automatically when so needed.
        * If heap cell can't extend a new cell is allocated, old data copied to
        * new cell and old heap cell deleted.
        *
        * Data is accessed and modified through base classes methods
        * CBufBase::Read(), CBufBase::Write(), CBufBase::InsertL() and
        * CBufBase::Delete(). Pointer access to data makes sence since data in
        * heap cell is continuous.
        */
        void FlatDynamicBuffersL();

        /*!
        * This example demonstrates how segmented dynamic buffers (CBufSeg) are
        * used to store and alter binary content. 8-bit character data is used
        * as an example data.
        *
        * CBufSeg splits contents to multiple heap cells having the same size.
        * These cells are called segments of the data. CBufSeg allocates new
        * segments automatically when data storage needs to be enlarged.
        * 
        * Data is accessed and modified through base classes methods
        * CBufBase::Read(), CBufBase::Write(), CBufBase::InsertL() and
        * CBufBase::Delete(). Pointer access is also possible but is difficult
        * since data isn't continuous (like in case of 
        */
        void SegmentedDynamicBuffersL();

        /*!
        * This example method demonstrates how to declare and use package
        * buffers and package pointers.
        *
        * In typical cases the threads can't access to each others memory areas.
        * However, interthread communication provides a way to read and write to
        * other threads memory. The memory address given for reading or writing
        * must be a descriptor. The actual reading and writing is done by kernel
        * that will make sure that descriptor constraints are respected: buffer
        * is not read or written before its starting index or after end index.
        *
        * Package buffer capsulates any value object as an binary array that
        * makes it easy pass object or structure of objects to other thread.
        */
        void PackageBuffers();
        
                
        /*!
        * Function demonstrates different usages of RBuf. 
        * It should be noted that the Create and Assign functions
        * leak memory if the memory for the RBuf isn't freed (i.e calling Close())
        * before calling them.
        * RBuf was introduced in Symbian OS 9 but was backported to Symbian OS 8.
        */
        void RBufDemonstrations();

    private: // attributes

        MResultViewer* iViewer; // not owned, just referred
    
    };

#endif // DESCRIPTOREXEXAMPLES_SYMBIAN_H
